.\"
.\" Copyright (C) 2016-2022  Davidson Francis <davidsondfgl@gmail.com>
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>
.\"
.TH man 3 "04 Apr 2022" "1.0" "wsServer man page"
.SH NAME
ws_socket \- Start the WebSocket server
.SH SYNOPSIS
.nf
.B #include <ws.h>
.sp
.BI "int ws_socket(struct ws_events " *evs ", uint16_t " port ", int " tloop ", "
.BI		uint32_t " timeout_ms " );
.fi
.SH DESCRIPTION
.BR ws_socket ()
starts the websocket server for the configured events
.IR evs ,
port number
.IR port .
and
.IR tloop .
The parameter
.I tloop
specifies if the accept loop should run on the same thread (if equals 0)
or on a different thread (if != 0).

Optionally, a user can set a pre-defined
.I timeout_ms
time (in milliseconds) that each message should have. Think of it like a 'ping':
if the client doesn't respond in x amount of time, the client is unresponsive
and the server shouldn't bother sending message to it.

In case of doubt, leave as 0.
.SH RETURN VALUE
If
.I tloop
is equals 0, this function blocks and never returns. Otherwise, returns 0.
.SH NOTES
.PP
The structure
.I evs
is defined as follows:
.nf
	struct ws_events
	{
		void (*onopen)(ws_cli_conn_t *client);
		void (*onclose)(ws_cli_conn_t *client);
		void (*onmessage)(ws_cli_conn_t *client,
			const unsigned char * msg,
			uint64_t size, int type);
	};
.fi

Each element corresponds to function pointers that are triggered when the
events occur.

The events:
.RS 2
.IP \(em 2
on_open: occurs when a client successfully connects and handshakes with the
server.
.IP \(em 2
on_close: occurs when a valid client (that handshaked with the server)
disconnects with the server. The reason is not informed.
.IP \(em 2
on_message: occurs when a client sends a message (whether txt or bin) to the
server.
.PP
Also note that the thread that sends the events is the same as that deals
with the client connection, so keep in mind that you need to let the
function return. If you want to perform further processing, consider
creating a new thread.
.SH SEE ALSO
.BR ws_sendframe_txt (3),
.BR ws_sendframe_bin (3)
.SH AUTHOR
Davidson Francis (davidsondfgl@gmail.com)
